Skip to content

Merge the two quick starts into one tabbed, video-free page and retit… - #424

Merged
ashera96 merged 4 commits into
wso2:mainfrom
veejask-41:improvement-ai-gateway-docs-423
Aug 11, 2026
Merged

Merge the two quick starts into one tabbed, video-free page and retit…#424
ashera96 merged 4 commits into
wso2:mainfrom
veejask-41:improvement-ai-gateway-docs-423

Conversation

@veejask-41

Copy link
Copy Markdown
Contributor

Summary

First phase of the AI Gateway docs revamp: collapses the two drifted AI Gateway quick starts into one canonical, tabbed, video-free page, and retitles the management API authentication page.

Refs #423

What changed

  • Merged the quick starts. llm-proxy/quick-start-guide.md is deleted and redirected to quick-start-guide.md. Everything unique to the deleted page moved across first: the port-conflict troubleshooting tip, the Podman runtime bullet, and the multi-runtime note. The runtime bullets gained official install links.
  • Platform tabs replace the stacked "Running on Windows" note. Five pymdownx.tabbed sets across the setup block and every curl block, so a Windows reader never reads commands that won't work.
  • Removed the video embed, moving the first command 13 lines up, above the fold.
  • Retitled Authentication and Authorization in Gateway ControllerSecure the management API, with the nav label updated to match.
  • Repointed six inbound references across overview.md, streaming-responses.md, next/index.md, llms.txt, and README.md.

Reviewing this diff

This is a restructure, not a rewrite. Every sentence that moved between pages arrives character for character identical, so any changed word in the diff is a deliberate, documented decision rather than incidental polish. Thirteen such deviations exist and are all listed in the implementation plan; the substantive ones are:

  • The Windows tabs' PowerShell comments swap setup.shsetup.ps1 and ExportSet.
  • The page now declares a PowerShell 7.3 minimum, and the test payloads use unescaped JSON. The \" escaping that a 5.1 reader needs actually breaks on 7.3+, where $PSNativeCommandArgumentPassing passes the argument through literally. 7.3 is the lowest version at which every command on the page is correct; 7.0–7.2 are past end-of-support.
  • The curl.exe explanation is scoped to Windows PowerShell, because PowerShell 7 removed the curl alias.

Verification

  • mkdocs build -c emits 45 warnings, identical to the pre-change baseline. The four known setup/configuration.md cross-reference warnings are deliberately still there.
  • All seven new runtime install links return HTTP 200.
  • Frozen version folders (1.0.0/, 1.1.0/, 1.2.0/) are untouched.
  • The redirect stub builds and resolves to the canonical page.
  • Every moved block was diffed against its source to confirm nothing was paraphrased.

Deliberately out of scope

  • Tab syncing is off. Selecting Windows (PowerShell) applies per tab set, not page-wide — content.tabs.link isn't enabled, and turning it on is a global change affecting every page.
  • README.md keeps its stale "LLM Quick Start Guide" link text; only the target was repointed.
  • Wording problems in moved text were flagged, not fixed. Thirteen items are qunt pass.
  • Nav restructuring, including refiling the auth page under Control Access, is in latter phase.

@coderabbitai

coderabbitai Bot commented Aug 10, 2026

Copy link
Copy Markdown

Review Change Stack

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: d78af510-dfcf-4018-8d35-8f9c9c674f5d

📥 Commits

Reviewing files that changed from the base of the PR and between 0d86963 and e2f15da.

📒 Files selected for processing (3)
  • .gitignore
  • en/docs/ai-gateway/next/README.md
  • en/docs/ai-gateway/next/quick-start-guide.md

📝 Walkthrough

Walkthrough

The AI Gateway documentation now uses one canonical quick-start guide with platform-specific instructions. Links and navigation point to the canonical guide, the former path redirects, and the Management API page uses updated naming.

Changes

AI Gateway documentation consolidation

Layer / File(s) Summary
Canonical quick-start guide
en/docs/ai-gateway/next/quick-start-guide.md
The guide adds runtime prerequisites and separate Linux/macOS and Windows PowerShell instructions for gateway, provider, and proxy setup and testing.
Documentation links and routing
en/docs/ai-gateway/next/README.md, en/docs/ai-gateway/next/overview.md, en/docs/ai-gateway/next/streaming-responses.md, en/docs/llms.txt, en/docs/next/index.md, en/mkdocs.yml, .gitignore
References use the canonical quick-start path. Navigation removes the former guide, and the former path redirects to the new guide. Documentation metadata dates and the .gitignore file were updated.
Management API naming
en/docs/ai-gateway/next/gateway-controller-management-api/authentication.md, en/mkdocs.yml
The page title, heading, date, and navigation label now use “Secure the management API”.

Estimated code review effort: 2 (Simple) | ~10 minutes

Possibly related PRs

Suggested reviewers: thushani-jayasekera

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Title check ✅ Passed The title clearly summarizes the primary change: merging the two quick starts into one tabbed, video-free page.
Description check ✅ Passed The description provides a detailed purpose, implementation approach, scope, references, and verification results for the documentation changes.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 12

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@en/docs/ai-gateway/next/gateway-controller-management-api/authentication.md`:
- Line 2: Update the corresponding entry in the LLM index to use the exact label
“Secure the management API,” matching the page title and navigation rename while
leaving its link and other index entries unchanged.

In `@en/docs/ai-gateway/next/quick-start-guide.md`:
- Line 133: Replace the capability-marketing phrase “first-class support” in the
OpenAI LLM provider documentation with neutral wording such as “supports” or
“includes support for,” including the corresponding occurrence elsewhere in the
document.
- Around line 59-60: Update the first setup comment to expand AES as “Advanced
Encryption Standard (AES)-256” while preserving the existing description; apply
the same terminology update to the corresponding comment at the second
referenced occurrence.
- Around line 104-106: Update the heredoc explanation in the quick-start guide
to apply only to the YAML-based management requests. Clarify that traffic-test
commands send JSON directly and do not require a heredoc, YAML file, Git Bash,
WSL, or the Windows PowerShell tab for YAML handling.
- Around line 216-226: Update all affected curl examples to clearly label -k as
local-development-only for the local HTTPS listener. Add guidance for non-local
use to validate TLS with a trusted certificate instead of disabling certificate
verification, covering the examples at the referenced sections.
- Line 17: Update the Markdown page heading from “Quick Start Guide” to sentence
case: “Quick start guide.”
- Line 29: Update the prerequisite wording in the quick-start guide to replace
the plus sign between the Docker Engine and Compose plugin links with the word
“and,” preserving the existing links and Linux qualifier.
- Line 23: Update the prerequisite introduction near the container runtime list
to use the complete sentence “Use one of these Docker-compatible container
runtimes:” and leave the following list unchanged.
- Around line 51-52: Update the download command in the Linux/macOS quick-start
setup to use curl with failure and redirect handling, saving to
wso2apip-ai-gateway-1.2.0-rc.zip, instead of requiring wget; keep the existing
release URL unchanged.
- Line 90: Update the setup command in the quick-start guide to invoke the
script with the documented PowerShell 7.3+ runtime, using pwsh or an equivalent
PowerShell 7 session instead of powershell.

In `@en/docs/ai-gateway/next/README.md`:
- Line 21: Replace the spaced hyphen in the link description at
en/docs/ai-gateway/next/README.md lines 21-21 with an em dash without
surrounding spaces; apply the same punctuation change at
en/docs/ai-gateway/next/overview.md lines 21-21.

In `@en/mkdocs.yml`:
- Line 666: Update the navigation label for authentication.md from “Secure the
Management API” to the page’s sentence-case title, “Secure the management API,”
while preserving the existing page path.
🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 77832299-add6-41bf-b050-88625725b392

📥 Commits

Reviewing files that changed from the base of the PR and between f1c4a29 and 9277cdd.

📒 Files selected for processing (10)
  • .gitignore
  • en/docs/ai-gateway/next/README.md
  • en/docs/ai-gateway/next/gateway-controller-management-api/authentication.md
  • en/docs/ai-gateway/next/llm-proxy/quick-start-guide.md
  • en/docs/ai-gateway/next/overview.md
  • en/docs/ai-gateway/next/quick-start-guide.md
  • en/docs/ai-gateway/next/streaming-responses.md
  • en/docs/llms.txt
  • en/docs/next/index.md
  • en/mkdocs.yml
💤 Files with no reviewable changes (1)
  • en/docs/ai-gateway/next/llm-proxy/quick-start-guide.md

Comment thread en/docs/ai-gateway/next/quick-start-guide.md
Comment thread en/docs/ai-gateway/next/quick-start-guide.md Outdated
Comment thread en/docs/ai-gateway/next/quick-start-guide.md Outdated
Comment thread en/docs/ai-gateway/next/quick-start-guide.md Outdated
Comment thread en/docs/ai-gateway/next/quick-start-guide.md Outdated
Comment thread en/docs/ai-gateway/next/quick-start-guide.md Outdated
Comment thread en/docs/ai-gateway/next/quick-start-guide.md
Comment thread en/docs/ai-gateway/next/README.md Outdated
Comment thread en/mkdocs.yml
@veejask-41
veejask-41 force-pushed the improvement-ai-gateway-docs-423 branch from 31ebfea to 28c2637 Compare August 11, 2026 04:32

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (1)
en/docs/ai-gateway/next/quick-start-guide.md (1)

354-354: 📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win

Use a direct verb in the Kubernetes next-step title.

Replace Take this gateway to production on Kubernetes with Deploy this gateway to production on Kubernetes.

As per coding guidelines, avoid idioms and figurative language, and write instructions directly.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@en/docs/ai-gateway/next/quick-start-guide.md` at line 354, Update the
Kubernetes next-step link title in the quick-start guide to use the direct verb
“Deploy,” replacing “Take this gateway to production on Kubernetes” while
preserving the existing link destination.

Sources: Coding guidelines, Path instructions

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@en/docs/ai-gateway/next/quick-start-guide.md`:
- Line 46: Update the documented version in the introductory text to match the
1.2.0-rc version used by the download URL, archive name, and directory name in
the commands below.

---

Outside diff comments:
In `@en/docs/ai-gateway/next/quick-start-guide.md`:
- Line 354: Update the Kubernetes next-step link title in the quick-start guide
to use the direct verb “Deploy,” replacing “Take this gateway to production on
Kubernetes” while preserving the existing link destination.
🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: ee90fa51-2cbc-4cdd-9d1b-e0a4c48aa215

📥 Commits

Reviewing files that changed from the base of the PR and between 9277cdd and 28c2637.

📒 Files selected for processing (1)
  • en/docs/ai-gateway/next/quick-start-guide.md

Comment thread en/docs/ai-gateway/next/quick-start-guide.md
@veejask-41
veejask-41 force-pushed the improvement-ai-gateway-docs-423 branch from ba27296 to 28c91b0 Compare August 11, 2026 04:49

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@en/docs/ai-gateway/next/quick-start-guide.md`:
- Line 126: Update the port-remapping guidance in the quick-start guide to
explicitly apply the remapped host port to all affected commands, including
provider and proxy management requests in the sections around the verification
and test commands. Ensure every command that targets host port 9090 uses the
configured replacement port.
- Around line 69-73: Update the “Start the complete stack” commands in the
quick-start guide to use detached Compose mode with `docker compose up -d` in
both platform tabs, allowing the subsequent gateway controller health check to
run once the controller is ready.
- Around line 23-33: Add curl and unzip to the Linux/macOS prerequisite list in
the quick-start guide, including installation guidance consistent with the
existing prerequisite format. Ensure the listed prerequisites cover the commands
used by the Linux/macOS instructions.
🪄 Autofix

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 1f10753c-9e4e-4743-a7d8-a4421453a644

📥 Commits

Reviewing files that changed from the base of the PR and between 28c2637 and 0d86963.

📒 Files selected for processing (5)
  • en/docs/ai-gateway/next/README.md
  • en/docs/ai-gateway/next/overview.md
  • en/docs/ai-gateway/next/quick-start-guide.md
  • en/docs/llms.txt
  • en/mkdocs.yml

Comment thread en/docs/ai-gateway/next/quick-start-guide.md
Comment thread en/docs/ai-gateway/next/quick-start-guide.md
Comment thread en/docs/ai-gateway/next/quick-start-guide.md
coderabbitai[bot]
coderabbitai Bot previously approved these changes Aug 11, 2026
Comment thread .gitignore Outdated
Comment thread en/docs/ai-gateway/next/quick-start-guide.md Outdated
Comment thread en/docs/ai-gateway/next/README.md Outdated
@ashera96
ashera96 merged commit d0c2388 into wso2:main Aug 11, 2026
2 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants